Celestin Apprentice 5/Apprentice-Release5.iso/Source Code/Libraries/ClutFade 1.3.2/Pascal/clut_fade 1.3.1 Pascal Notes

Text File | 1996-03-06 | 5KB | 141 lines

CLUT Fade 1.3 - Pascal Version Notes

Hi everyone. Yesterday I took it upon me to convert the ugly
C cryptography into something that resembles code. Since it was
not pretty to begin with and I did a straight port, don't
look here for shining examples of elegant coding. It's ugly.
It's dirty. It's baaad. It works.

The Pascal code is reasonable readable (in contrast to the
C original) and works as good as the C version. The original
was written by Jonas Englund, Mark Womack ([e-mail])
and Macneil Shonle ([e-mail]), so any kudos for the
routines are due to them. I just happened to be around and did
the port.


Porting Notes:
==============
The pascal conversion was written for THINK Pascal, so you
might run into some problems when porting it to MW Pascal
(very probably with the 'CYCLE' statement). Other than that
the routines should port all right (if you also port the
demo program, be sure to change @thePort to qd.thePort).

Below you will find some notes on a few more peculiar
points of interests inside the fade port and how they
came about. You may easily skip the rest of this document
if all you want is the fade functionality without knowledge
about it's inner workings.
However, since I'm a Pascal advocat, the comments you find
here focus only on the aspect of porting the C version to
Pascal. You won't find an explanation of how the fade routines
actually work, just how they were ported. To discover the
former, read the code. Remember: 'Code doesn't have to be
commented -- it's obvious' (plus, 'if it was hard to write
then it should be hard to read').


Elegance Factor: Low
--------------------
The Pascal code seems to be unreasonable convoluted. This is
not because I'm a bad programmer (which may be true :-)
but because it is a direct 1:1 port of the original C code.
For example, most of the

    i:=0;
    WHILE expr(i) DO BEGIN
        ...
        i := i + 1;
    END;

loops would have been much better coded through a FOR block.
Actually, all of these loops originally *where* FOR loops in
C. But in C a loop can have conditions as boundaries; so for
the sake of clarity, I chose to implement them through WHILE.


Eat my shorts!
--------------
If you compare the C and Pascal sources side to side, two things
are immediately appearent:

    1. Pascal looks much better although/because it's more eloquent

    2. These mysterious BitANDs!

Number one is obvious and the reason you are reading this in the
first place. Number two has to do with one of the most annoying
shortcomings of the Pascal semantic: no provisions for unsigned
integers. This is usually not a problem since you can always use
longints when dealing with numbers larger than 32766. There is one
exception, though: RGB colors range from 0-65535 ($0000-$FFFF) in
Red, Green and Blue and their field type is integer. To set a
value to max you can pass $FFFF. When you read it, though, it
returns a '-1' (correctly, since this is two's complement integer
arithmetic). This is bad because now you can't use the rgb
value as a CONSISTENT upper/lower boundary for fading (for
example, when fading from Gray ($A000) to Black ($0000)).
Typecasting integer to longint does not do the trick because
Pascal cleverly extends the last bit (#15) to bits 16 to 31
to preserve the value (thus a -1 integer won't turn to +65535
longint). This is the reason why you will find those mysterious

    color := BitAND(color,$0000FFFF);

statements. They simply undo the results of the extension of
bit 15. After the BitAND a -1 integer is a 65535 longint. Now
we can add/subtract and compare to heart's content. To avoid
the same problem when going back from longint to integer, I
simply used the LOWORD function to copy the lower 16 bits
into integer.

C does not have this problem since it provides a variable of
type SHORT that is actually an unsigned integer. This is about
the only time where I saw C at an actual advantage. OTOH, Nikki
must have recognized this minor flaw when he designed MODULA-2
because -- lo and behold -- it sports a CARDINAL variable type.


Order reversed
--------------
C and Pascal have radically different approaches to programming.
While in C you just go ahead and program whatever enters your
mind you must pause and think first in Pascal. To call a procedure
it must have been previously defined. Not so in C. Therefore
you find the explicit main program in C at the beginning while
it's at the very end in Pascal. This forced me to either alter
the sequence of functions or use FORWARD declarations. Of both
options, the former is more elegant but destroys the 1:1
relationship of C and Pascal sources (bad for editing). Thus,
I chose the latter in the fade routines themselves, while I
happily rearranged the procedures in the not-so-critical
demo sources.



Parting Notes
=============
I hope you can use the fade routines. I found them to be very
nice and bow to the original authors for a fine piece of work.
Any comments/suggestions for improvements should be directed
to Mark Womack ([e-mail]) or Macneil Shonle
([e-mail]).

If you have any questions regarding the Pascal version, email
me at [e-mail]


Cheers,
Christian

Zürich, 05-MAR-96



"Ankh-Morpork has a technical democracy: On Man, One Vote.
In Ankh-Morpork, the Patrician is that Man. His rule is not so
much a reign of terror, but the occasional shower."

Terry Pratchett - Discworld